Install the {distill} package from CRAN:
install.packages("distill")
Clone the ala-labs repository to a local directory.
We use a custom file to build the website. To build the website, run
the code in R/ignition_sequence.R.
If successful, to see the built website navigate to your local file
explorer and opening _site/index.html.
We use a custom file to build the website because we have added
several bespoke features to the standard distill website format (like
auto-updating lists in _people pages and a custom search
toolbar). Adding these features means that using the recommended method
by {distill} to
use the Build Website tab in the Build pane no longer
works. Only using rmarkdown::build_site() will also not
work correctly.
When you build the website, the following things occur:
All of the Rmd and md files in the root
website directory will be rendered into HTML. Note, however, that
markdown files beginning with “_” are not rendered (this is a convention
to designate files that are included by top level documents, or in other
words, distill knows not to overwrite these folders because they are
important).
Posts will be copied into the _site/posts
sub-directory. Pages with post listings will be re-generated.
The generated HTML files and any supporting files (e.g. CSS and
JavaScript) are copied into the _site directory.
The top 3 most recently written Posts will be added to the
author’s _people page. (Note: For the website to build,
ensure that all people who have authored a post have their own People
page, even if this page is not accessible to the public)
The HTML files within the _site directory are built and
ready to deploy as a standalone static website.
The _site folder has all of the information needed for
the static website. The ALA web hosting service has been told to publish
what is in the _site folder on the master branch to .
When you are happy with changes or updates to the website, make sure
your changes to the _site folder are pushed to the master
branch.
Updates to the website should be added to the dev branch
of the GitHub repo. In the dev branch, any changes made
will not be published to the existing website. The dev
branch effectively works as a test site prior to deployment.
Top-level web pages (the ones people see in the top navigation bar)
are saved in the top-level folder by their page name (for example, the
content for the About page is in about.Rmd).
Additional pages can be added by creating a new R Markdown page in the main website folder with the yaml header:
---
title: ""
description: |
description-goes-here
output:
distill::distill_article:
css: theme.css
---
Pages can then be added to the website by their text and
href to the site navigation in _site.yml under
navbar (see Site
Output and Navigation)
Posts are written in R markdown files. Post templates can be found in
the templates folder.
To create a new post:
Create a new folder in the _posts folder. The folder
name should be the date and title of your article (for example,
2022-02-17_sunburst-plots-for-taxonomic-data
In your new post folder, save your Post file. You are welcome to
use a simple name for your Rmd file (for example,
sunburst-plots.Rmd)
Be sure that you have filled in all the necessary information about your post in the yaml header and in the author card section
Write your post
Render/Knit your document using the
R/render_post.R document. Using the code in
R/render_post.R allows you to avoid adding personal
information to your Post (like your personal email in
galah_config()). The most recently knitted version of your
file is what will appear on the website
When you are happy with your post, build the website. After the website it built, your rendered post should appear in the Posts listing page
Distill uses a CSS framework that can be fully customised. CSS theme
settings are in theme.css. See the Distill
website page for instructions on how to edit additional website
properties.
Some properties can be found in labeled sections, like settings for
website fonts, header and footer sections. For example, website header
settings can be found in the .distill-site-header
section:
/*-- WEBSITE HEADER + FOOTER --*/
/* These properties only apply to Distill sites and blogs */
.distill-site-header {
--title-size: 18px;
--text-color: #ff414b; /* edited */
--text-size: 15px;
--hover-color: #dd424c; /* edited */
--bkgd-color: #ffd8db; /* edited */
}
Other properties are edited using custom CSS. These are (mostly)
labelled and relate either to built-in distill html elements or html
elements built in R/function.R.
R/functions.R contains functions that create html
elements within the ALA Labs website. R/functions.R uses
the {htmlTools}
package to write html code using R syntax.
For example, the following R function and html code are equivalent.
They both will create a link of class = "article-link".
This class name can be used with CSS in theme.css to edit
the element style.
#<!-- html -->
#<a class = "article-link" href = "https://ala.org.au/">my text</a>
# R function
add_link_to_article <- function(title, url){
tags$a(
class = "article-link",
href = url,
"text"
)
}
add_link_to_article(text = "my text", url = "https://ala.org.au/")
The benefits of writing R functions to create html elements are:
Rather than trying to edit html elements that the Distill package runs in the back-end to build the website, adding html elements using R functions is easier and less prone to errors
It is easier for people familiar in R to reuse and edit the content of existing html elements created by R functions
To use functions in the R/functions.R file on a specific
website page or post, the following code block must be added below the
YAML header
```{r, include=FALSE}
library(htmltools)
source("R/functions.R")
```